Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / tchasm.arc / TCHASM.DOC < prev next >

Wrap

Text File | 1980-01-01 | 41.9 KB | 1,014 lines

These are documents copied from CHASM by David Whitman and are provided only because TChasm is a Turbo Pascal version of CHASM. I copied David's program almost word for word. (converting to pascal when necessary) I have placed comments in these notes preceded by {!} to note changes. The editor included with TChasm is the FIRST-ED from Borland International's Turbo Editor Toolbox (tm). I deleted all of the ^O commands as well as those referring to markers. (See table of editing commands that follow) I have left intact the WordStar (tm) commands and have included some additional commands, which I prefer. The Toolbox is well worth its cost. I have provided only the source code for the assembler and the hooks into the editor. The only significant change I have made to the editor routines is adding an OK := true; (or false) in the EditReaTxtFil procedure to see if there was enough memory left after loading the source file into memory. (I leave this bit of coding to you) To compile the program, you will need the Editor Toolbox. Merge VARS.PAS into VARS.ED and INIT.PAS into INIT.ED. Comment out any code relating to Window commands (the O-commands) and Markers, otherwise the resulting code will be too large and you will need to use overlays. Make the above change to EditReaTxtFil. I have made changes to EditKeypressed to allow the various keys to have new meanings. I've been able to compile and run from memory the program on an IBM PC with 256K. If you have a computer with little memory, you may want to change the program to have overlays. (I would suggest swapping the editor and assembler routines in and out of memory) I don't care for overlays because you must stay in one directory - Well, actually you don't, but I didn't want to write the extra code necessary. (see MicroStar included with the Editor Toolbox) As I am placing this program out here for public use, don't send me any money. If you feel it is of any use or value, send a donation to Mr. Whitman. He has obviously worked very hard to develop CHASM and I am indebted to him for not forcing me to pay for it. I would like to hear about any bugs (egads!) or improvements you may discover. This is only Version 1.0, so I'm sure there will be updates. (I would really enjoy hearing about a way to make this a single pass assembler, if it is at all possible) Please write and let me know how you like it. (by not paying me, I also stipulate that YOU not sell this program to anyone either) Mark Streich 1160 Glen Arbor Ave. Los Angeles, CA 90041 P.S. I can be reached on the ECANET RBBS (seems to be one of the few BBS's around that I am able to get on often enough to check messages) at 818-896-7450. Editor Commands (use of arrow keys or control keys is up to you) --------------- ^A [^Left] Left Word ^F [^Right] Right Word ^S Left Char ^D Right Char ^E Up Line ^X Down Line ^C [PgDn] Down Page ^R [PgUp] Up Page ^W Scroll Up ^Z Scroll Down ^Y Delete Line ^N Insert Line ^G [Del] Delete Char ^P Insert Ctrl Char ^I [Tab] Tab ^T Delete Word ^V [Ins] Toggle Insert ^L [F4] Repeat Last Find or Replace [Esc] Undo (after delete lines - 20 lines max) ^Q^C [^PgDn] End of File ^Q^R [^PgUp] Top of File ^Q^B To Beg. Block ^Q^K To End of Block ^Q^A [F3] Find/Replace ^Q^F [F2] Find ^Q^D [End] End of Line ^Q^S [Home] Start of Line ^Q^I Auto Indent ^Q^Y Delete to End of Line ^K^B [F7] Begin Block ^K^K [F8] End Block ^K^C Copy Block ^K^V Move Block ^K^Y Delete Block ^K^H Hide Block ^K^R Read File ^K^W Write Block ^K^D [F1] Quit Edit ^K^T Set Tab Width ^K^S Save File (from within Editor) Main Screen Functions are all fairly self-explanatory. L - Logged Directory, changes current directory W - Work File, Changes current working file (assumes .ASM extension) O - Output Location, Lists output to either Screen, Printer, a File, or none. (You will get a progress status on screen) The program always creates a .COM file even if there are errors. You will need to exit TChasm to run them. (I can't replicate Turbo Pascal!) File Location - Just lets you know whether the file is in memory or on the disk. (it is on Disk whenever there isn't enough memory to hold it) E - Edit, Takes you into the editor if there is enough memory to hold the file. S - Save the file which is currently in memory. The Editor does NOT make a .BAK file when saving. If you want to be safe, do a Block Write to another file. A - Assemble, begins the two-pass assembling of the work file. D - Directory, (from Turbo Tutor by Borland Int'l.) Could have used some of the other public domain directory listers, but this one works fine. Q - Quit, If changes have been made to file, will prompt for saving. The program KAZOO.ASM is for your amusement and practice. It is copied from Robert Lafore's "Assembly Language Primer for the IBM PC & XT." I have found the book easy to read and useful. Now that I've written an assembler, I intend to learn assembly language. {CHASM.DOC by David Whitman begins here.} NOTE: You can print out this file by pressing CTRL PrtSc and then: TYPE CHASM.DOC. Before you do, note the following: 1. The documentation is about 30 pages long - have lots of paper ready. 2. If your printer has a condensed (132 column) mode, turn it on before printing. If you do, the resulting pages can be cut down to 5 1/4 X 8 1/2 inches to fit in an IBM document binder. If you do not have access to a printer, the author will provide a copy of the documentation for $5. The $5 fee covers the cost of Xeroxing and mailing, and is not included in the $20 suggested donation. (tm) CHASM Cheap Assembler for the IBM Personal Computer (1983) by David Whitman Version 1.9 Table of Contents Why Chasm?...........................................2 What can Chasm do?...................................3 What WON'T it do?....................................3 Syntax...............................................4 Operands.............................................6 Resolution of Ambiguities...........................10 Pseudo-Operations...................................13 Outside the Program Segment.........................16 Running Chasm.......................................18 Error and Diagnostic Messages.......................20 Execution of Assembled Programs.....................23 Notes for Those Upgrading to This Version of Chasm..26 Miscellaneous and A Word From Our Sponsor...........28 I. Why Chasm? Why go to the trouble to write an assembler, when one already exists? The IBM Macro Assembler is a very powerful software tool available off the shelf. It supports features such as macros, definition of multiple segments, and linking to external procedures. Unfortunately, all of this power doesn't fit into a 64K machine, and even when using the small subset version, 64K users are limited by memory to only very small programs. The macro assembler is also very complex, hard to understand, and costs a hundred bucks. Even though the price of memory keeps dropping, I suspect that the majority of the IBM PC's out there have no more than 64K installed. Also, I suspect that most end-user assembly language programmers are like myself, and are not interested in writing huge, complicated programs in assembler. I want to write short subroutines to call from BASIC, small patches to existing assembler programs (such as DOS), and perhaps some games. For such uses, I think the combination of the Macro Assembler and a tub full of extra memory represents an incredible overkill. Chasm is, I hope, a more reasonable compromise between power and accessability (both in cost and complexity). II. What can Chasm do? Chasm takes a text file, consisting of mnemonics, user-defined symbols, numbers, and pseudo-ops, and produces a file of corresponding machine language for the 8088 processor. Chasm allows you to define labels for branching, rather than requiring you to figure out offsets or addresses to jump to. It allows you to represent with a name any constants you want to use, making your programs easier to understand. Most importantly, it translates mnemonics to their machine language equivalents freeing you from the task of hand translation. III. What WON'T it do? In the interest of simplicity, Chasm has a number of restrictions: 1. Statement syntax is not quite as free as in the macro assembler. 2. The number of pseudo-ops is severely cut down from the macro assembler. 3. Macros are not supported. (Note that the IBM assembler doesn't support macros in systems smaller than 96K) 4. Expressions (such as BUFFER - 2 ) are not supported, at least in version 1.0. 5. Multiple segment definitions are not allowed, at least in version 1.0. Chasm assumes that your entire program fits in one segment, that the cs, ds, and es registers all point to this same segment, and that the ss register points to a valid stack area. 6. External linking is not supported, at least in version 1.0. IV. Syntax Chasm accepts a standard DOS text file for input. Lines may be any combination of upper and lower case characters. Chasm does not distinguish between the two cases: everything except single quoted strings are automatically converted to upper case during the parsing process. Thus, BUFFER, Buffer, buffer, and bUFFer all refer to the same symbol. The characters blank ( ) , comma (,), single quote (') and semi-colon (;) are reserved, and have special meaning to Chasm (see below). {!} TChasm uses the first character found in the second line of TChasm.DAT as the Quote character. This can be any character you want. So if you don't like the default of a Double Quote, change it. Each line must be less than 256 characters long and have the following format: Label Operation Operand(s) ;comment The differant fields of an input line are separated by the delimiters blank ( ) or comma (,). Any number of either delimiter may be used to separate fields. Explanation of Fields: Label: A label is a string of characters, beginning in column 1. Depending on the operation field, the label might represent a program location for branching, a memory location, or a numeric constant. Note that anything beginning in column 1, except a comment, is considered a label. Operation: Either a pseudo-op (see section VII) or an instruction mnemonic as defined in "The 8086 Book" by Rector and Alexy. Note 1: Except as modified below,"The 8086 Book" is the definitive referance for use with Chasm. Note 2: There are several ways to resolve some ambiguities in 8086 assembly language. Please read page 3-285 of The 8086 Book, and section VI of this document. Operand(s): A list of one or more operands,as defined in section V, separated by delimiters. Comment: Any string of characters, beginning with a semicolon (;). Anything to the right of a semicolon will be ignored by Chasm. Note that except for the case of an operation which requires operands, or the EQU pseudo-op which requires a label, all of the fields are optional. The fields MUST appear in the order shown. V. Operands The following operand types are allowed. 1. Immediate data: A number, stored as part of the program's object code. Immediate data are classified as either byte, expressable as an 8 bit binary integer; or word, expressable as a 16 bit binary integer. If context requires it, CHASM will left-pad byte values with zeroes to convert them to word values. Attempts to use a word value where only a byte will fit will cause an error message to be printed. Immediate data may be represented in 5 ways: A. An optionally signed decimal number in the range -32768 to 32767. Examples: MOV AL,21 MOV BX,-6300 B.1. A series of up to 4 hex digits, followed by the letter H. Examples: ADD CX,1234H ADD DL FDH {!} B.2. A series of binary digits followed by letter B. ADD CX,11110111B C. A symbol representing types A or B above, defined using the EQU pseudo-op. Examples: MASK EQU 10H MAX EQU 1000 AND CL,MASK SUB AX,MAX D. The offset of a label or storage location returned by the OFFSET operator. OFFSET always returns a word value. OFFSET is used to get the address of a named memory location, rather than its contents. Example: MOV DI,OFFSET(BUFFER) BUFFER DS FFH E. The ASCII value of a printable character, represented by the character enclosed in single quotes ('). Thus, the following lines will generate the same object code: {!} Any quote Character you want for Tchasm. (see opening remarks) Default is Double Quotes rather than single Quote. MOV AL,41H ;ascii code for 'A' MOV AL,'A' 2. Register Operands: One of the 8088's internal registers. A. An 8 bit register from the following list: AH AL BH BL CH CL DH DL B. A 16 bit register from the following list: AX BX CX DX SP BP SI DI C. A segment register from the following list: CS SS DS ES 3. Memory Operands: The contents of a memory location addressed by one of the following methods. Note that none of the memory adressing options specifies the whether a byte or word operand is being referanced. See section VI for more on this topic. A. Direct address. 1. A number, or symbol representing a number, enclosed in brackets, indicating an offset into the data segment. Example: BUFFER EQU 5A5AH MOV BH,[BUFFER] MOV [80H],DI 2. A symbol, defined to be a variable (i.e. a named memory location) using the EQU pseudo-op. Example: FCB EQU [80H] MOV DI,FCB 3. A symbol, defined to be a variable by its use on a storage defining pseudo-op. Examples: MOV AX,FLAG MOV DATE,BX FLAG DS 1 DATE DB 31 B. Indirect Address: The address of the operand is the sum of the contents of the indicated register(s) and a displacement. The register, or sum of registers, are enclosed in square brackets: [] The displacement is optional, and takes the form of an immediate operand, placed without intervening delimiters to the left of the first bracket. Displacements in the range -128 to 127 (i.e. hex 0 - 7F, FF80 - FFFF) are interpreted as signed 8 bit quantities. All other displacements are interpreted as unsigned 16 bit quantities. (Note that although the 8088 supports unsigned 16 bit displacements up to hex FFFF for indirect adressing, Chasm isn't smart enough to distinguish between -1 and FFFFH.) The following indirect modes are allowed: 1. Indirect through a base register (BX or BP). Examples: ENTRYLENGTH EQU 6 MOV AX, ENTRYLENGTH[BP] MOV DL, -2[BX] MOV CX, [BP] MOV 9A9AH[BX], AX 2. Indirect through an index register (DI or SI). Examples: MOV [DI], CX MOV CX, -5[SI] 3. Indirect through the sum of one base register and one index register. Examples: MOV [BP+DI], SP ;note that no spaces are MOV BX, 10H[BX+SI] ;allowed within the MOV CL, [BP+SI] ;brackets. MOV DH, -2[BX+DI] 4. Labels A label on a machine instruction may be used as an operand for call and jump instructions. Examples: START PROC NEAR CALL GETINPUT JMPS START ENDP GETINPUT PROC NEAR 5. Strings A string is any sequence of characters (including delimiters) surrounded by single quotes ('). {!} Any character you want for TChasm ( "Copyright May 15, 1985" ) Example: DB 'Copyright May 15,1982' VI. Resolution of Ambiguities. The language defined in "The 8086 Book" contains a number of ambiguities which must be resolved by an assembler. This is discussed throughout the book, but pages 3-285 and 3-286 specifically cover this topic. Chasm's solutions of these problems are discussed in this section. A. Memory referances: When one specifies the address of a memory location, it is unclear how large an operand is being referanced. An operand might be a byte, or a word. 1. If a register is present as an operand, it is assumed that the memory operand matches the register in size. An exception to this rule are the shift and rotate instructions, where the CL register is used as a counter, and has nothing to do with the size of the other operand. Examples: MOV MASK,AX ;mask is a word MOV DH,[BX] ;BX points to a byte NEG [SI] ;error, operand of unknown size SHR FLAG,CL ;error, flag is of unknown size 2. If no register is present, (or if the only register is CL being used as a counter) the size of the memory operand is specified by adding the suffix "B" or "W" to the instruction mnemonic. Examples: NEGB [SI] ;SI points to a byte SHRW FLAG,CL ;flag is a word MOVW MASK,0AH ;mask is a word MOVB MASK,0AH ;mask is a byte MOVW MASK,9A9AH ;must specify size even though ;immediate operand implies word MOVB DH,[BX] ;error(!), register already ;specifies size B. Indirect Branching. The 8088 supports two flavors of indirect branching: intra, and inter segment. A register is set to point at a memory location which contains a new value for the program counter, and in the case of intersegment branching, a new value for the CS register as well. The syntax of "The 8086 Book" does not specify which flavor of branch is being invoked. Chasm adds the suffixes "N" (for near, or intrasegment) and "F" (for far, or intersegment) to the indirect CALL and JMP mnemonics. Examples: CALLN [BX] ;intrasegment call JMPF [DI] ;intersegment jump JMP [BP] ;error, unspecified flavor C. Long and Short Jumps Two types of relative jumps are supported by the 8088: short (specified by a signed 8 bit displacement) and long (specified by an unsigned 16 bit displacement). Both are implemented in Chasm as a jump to a label. The short jump is specified by mnemonic JMPS, in accord with the IBM disassembler, but not with The 8086 Book, which uses JMP. Since one of the displacement bits is used as a sign bit, only seven are left to express the magnitude of jump. JMPS (and similarly, all the jump on condition instructions) is thus limited to branching to labels within a range of -128 to +127 bytes. Chasm reserves mnemonic JMP for the long jump. Note that JMP may only be used to jump in the forward direction, since the sixteen bit displacement is unsigned, and assumed to be positive. Examples: START PROC NEAR JMPS START ;short jump JMPS END ;short jump JMP END ;long jump JMP START ;error: reverse long jump END ENDP D. Instruction Prefixes. The 8088 supports three instruction prefixes: 1. SEG: segment override. An alternate segment register is specified for a referance to memory 2. REP, REPE,REPNE,REPZ,REPNZ: repeat. A string primitive is repeated until a condition is met. 3. LOCK: Turns on the LOCK signal. Only useful in multiprocessor situations. Chasm implements these prefixes as separate instructions, rather than prefixes to another instruction. They appear on a separate line, immediately before the instruction which they modify. This is in accord with the output of the IBM disassembler, but not with the IBM macro assembler. Examples: SEG ES MOV AX,FLAG ;flag is in the extra segment REP MOVSB ;move bytes until CX decremented to 0 VII. Pseudo-Operations The following pseudo-ops are implemented: A. DB: Declare Bytes Memory locations are filled with values from the operand list. Any number of operands may appear, but all must fit on one line. Acceptable operands are numbers between 0 and FFH (0-255 decimal), or strings enclosed in single quotes ('). If a label appears, it is considered a variable, and the location may be refered to using the label, rather than an address. Examples: MOV AX,MASK MASK DB 00H,01H STG DB 'A string operand' B. DS: Declare Storage Used to declare large blocks of identically initialized storage. The first operand is required, a number specifying how many bytes are declared. If a second operand in the form of a number 0-FFH appears, the locations will all be initialized to this value. If the second operand is not present, locations are initialized to 0. As with DB, any label is considered a variable. To save space, the object code does not appear on the listing. Examples: DS 10 ;10 locs initialized to 0 DS 100H,1AH ;256 locs initialized to 1AH C. ENDP: End of Procedure See PROC (below) for details. D. EQU: Equate Used to equate a symbolic name with a number. The symbol may then be used anywhere the number would be used. Use of symbols makes programs more understandable, and simplifies modification. An alternate form of EQU encloses the number in square brackets: []. The symbol is then interpreted as a variable, and may be used as an address for memory access. This version is provided to allow symbolic referance to locations outside the program segment. Warning: Difficult to debug errors may result from using a symbol prior to its being defined by EQU. I strongly urge that all equates be grouped together at the beginning of programs, before any machine instructions. See "Phase Error" in section IX. Examples: MOFFSET EQU B000H MONOCHROME EQU [0000H] E. ORG: Origin Allows direct manipulation of the location counter during assembly. By default, Chasm assembles code to start at offset 100H, the origin expected by COMMAND.COM for .COM programs. Using ORG you may override this default. Example: ORG 0 ;Code will be assembled for starting ;offset of 0 F. PROC ...ENDP: Procedure Definition Declares a procedure. One operand is required on PROC, either the word NEAR, or the word FAR. This pseudo-op warns Chasm whether to assemble returns as intra (near) or intersegment (far). Procedures called from within your program should be declared NEAR. All others should be FAR. ENDP terminates the procedure, and requires no operands. If a RET is encountered outside of a declared procedure, an error occurs. Procedures may be nested, up to 10 deep. Example: MAIN PROC FAR ... ... ;body of procedure ENDP VIII. Outside the Program Segment As mentioned previously, Chasm does not support multiple segment definitions. Provision is made for limited access outside of the program segment, however. A. Memory Referances To access memory outside the program segment, you simply move a new segment address into the DS register, then address using offsets in the new segment. The memory option of the EQU pseudo-op allows you to give a variable name to offsets in other segments. For example, to access the graphics charactor table in ROM: BIOS EQU F000H CHARTABLE EQU [FA6EH] MOV AX,BIOS ;can't move immed. to DS MOV DS,AX MOV AL,CHARTABLE ;1st byte of char. table B. Code Branching Chasm supports 4 instructions for branching outside the program segment. 1. Direct CALL and JMP New values for the PC and CS registers are included in the instruction as two immediate operands. Example: BIOS EQU F000H ;RAM bios segment DISKETE_IO EQU EC59 ;disk handler JMP DISKETE_IO,BIOS 2. Indirect CALLF and JMPF Four consecutive bytes in memory are initialized with new values for the PC and CS registers. The CALLF or JMPF then referances the address of the new values. Example: BIOS EQU F000H ;RAM bios segment PRINTER_IO EQU EFD2H ;printer routine MOV [DI],PRINTER_IO MOV 2[DI],BIOS CALLF [DI] {!} Running Tchasm : Type TChasm (TChasm.Dat and TChasm.Msg must both be in same directory). You will be greeted with a message and then the main screen. This is where you get to all the features. After assembling, you will be back at the Main Screen. (maybe somebody can figure out how to let assembly language programs run from within TChasm - Probably has a lot of changing of interrupts etc.) If there are any errors listed however, I would suggest you not run your program. (Even if you pick no Output, you will be given a message about how many errors were detected. X. Error and Diagnostic Messages Error messages generated on pass one appear on the listing before any source code is printed, and mention the line number to which they refer. The majority of messages occur during pass two, and will appear in the listing immediately prior to the line which caused the message. Could Use JMPS: Diagnostic. The specified label requires an offset of less than 128 bytes; specifying the short jump would result in more compact code. The assembled code is correct, however. Data too Long: The value of a immediate byte is found not to be in the range 0-FFH Duplicate Definition of XXX in (linenum): Pass 1 error. An attempt was made to define a symbol already present in the symbol table. ENDP without PROC: An ENDP was encountered, but no corresponding PROC was found. EQU Without Label: No symbol was found to equate with the operand Illegal or Undefined Argument for Offset: The argument for the Offset function was not present in the symbol table as a near label or memory location on pass 2. Illegal Reverse Long Jump: Long jumps must in the forward direction, since they are expressed with an unsigned displacement. Missing ENDP: The end of the input file was encountered, and at least one PROC had not been terminated by an ENDP. Phase Error: A near label or memory location is found to have differant values on pass 1 and pass 2. A difficult to debug error: generally the problem is not caused by the statement which received the error message. The only documented way to generate this error is by using a symbol prior to defining it using EQU. On pass 1, Chasm assumes that unrecognized symbols are either labels or memory addresses which will be defined later in the program. If the symbol is subsequently defined as immediate data, the location counter may get all messed up. I would appreciate hearing about any other situations which cause this message to appear. Procedures Nested Too Deeply: Procedures may be nested no more than 10 deep. Specify Word or Byte Operation: Diagnostic. Chasm suggests that the Syntax Error might be resolved by adding the suffix "B" or "W" to the instruction mnemonic. Most, but not all, ambiguous memory referances are flagged with this diagnostic. Syntax Error: (OP) (DTYPE) (STYPE). Chasm was unable to find a version of the instruction (OP) which allows the operand types (DTYPE) and (STYPE). Either the instruction doesn't exist, or it is misspelled, or it is an inappropriate choice for the given operands. DTYPE and STYPE are numbers which encode Chasm's guess as to what the 1st and 2nd operands might be. The numbers are sums of the types given in the following list: 1 = 8 bit accumulator 2 = 16 bit accumulator 4 = 8 bit register 8 = 16 bit register 16 = a register or indirect 32 = CS register memory referance 64 = other segment register 128 = memory location 256 = immediate byte 512 = immediate word 1024 = none 2048 = string 4096 = near label 8192 = far label 16384 = CL (count) register Too Far For Short Jump: The displacement to the specified label is not in the range -128 to +127. Too Many User Symbols in (linenum): Pass one error. The symbol table is full. Undefined Operand for EQU: Any operands on an EQU statement must have been previously defined. Undefined Symbol XXX: The symbol XXX was used as an operand, but never appeared as a label, and is not a predefined symbol. Unrecognized Operand XXX: XXX is used in the DB operand list, but is not a string or byte value. XI. Execution of Assembled Programs A. Object code format The object code file produced by CHASM is in the form of a memory image, exactly as will be present in your computer at run time. No link step is required. Provided that the segment registers are set correctly, the architecture of the 8088 guarantees that code is self-relocating, and will run correctly loaded anywhere in memory. Storing a program as an exact image of memory at run time is called the COM format by IBM. This COM format is *not* that produced by the IBM assembler. The output of the IBM assembler is in the form of an "object module" suitable for input to the linker. To the best of my knowlege, the object module is not directly executable, but must first be "filtered" through the linker. This adds an extra step to the process of producing a working program, but gives you the option of combining multiple object modules into one program. The resulting linked program is *still* not a memory image, but has a header which is used to perform relocation during loading. This linked program plus header is called the EXE format by IBM. B. Running Assembled Programs From DOS DOS provides a loader for running machine language programs. To run a program, you merely type it's name, with or without the extension. This is what you're doing every time you use a DOS external command such as FORMAT or CHKDSK. In fact, the COM format is named after "external COMmand". When you type the name, DOS examines the file extension to determine what format the file is in, either COM or EXE. This is why CHASM defaults to using the extension .com for your object file. If you plan to run the program from DOS, don't change the extension. For COM programs, DOS builds a 255 byte long "program segment prefix" and sets the segment registers to point to this PSP. The contents of the file are then loaded verbatim right after the PSP, at offset hex 100 in the segment defined by the segment registers. As soon as loading is complete, your program is executed starting with the instruction at hex 100. Although you can totally ignore the PSP, you should read pages E-3 through E-11 of the DOS manual to see what DOS puts there for you. It turns out there are some real goodies which your program might want to use. When your program is done, it must transfer control back to DOS, otherwise the 8088 will continue to fetch what it believes are instructions from whatever garbage or bit-hash happens to follow your program in memory. The easiest way to return to DOS is to execute the instruction: INT 20H This is the vectored interrupt reserved by DOS for program termination. While we're on the topic of vectored interrupts, you would be well rewarded to study both the DOS manual and Technical Referance to find out what happens when you execute some of the other interrupts. Some very useful functions, such as file handling and screen i/o, are available at the machine language level through this mechanism. By changing the interrupt vector for a given function to point to your own code, you can overide the way DOS or the BIOS does something, and do it your way. This document was produced from Easywriter directly, in standard DOS format, by printing it to disk. It was not necessary to manually add an end of paragraph marker at the end of each line, and I didn't need to run it through the program TRANSFER which IBM provides. I had changed the vector for printer support to point to some code which sent the output to disk. Easywriter thought it was using the printer, and formatted everything nicely. C. Debugging Assembled Programs IBM provides an excellent utility with DOS, called DEBUG.COM. By specifying your program's name as a parameter when invoking DEBUG, you can observe your program execute with DEBUG's trace and other functions. To debug your program from DOS, type: DEBUG progname.COM DEBUG builds a PSP and loads your program just like DOS does, but you have the added power of the debugging commands to monitor your program while it runs. See chapter 6 of the DOS manual for more details about using DEBUG. D. Using Assembled Programs in BASIC To incorporate a machine language subroutine in a BASIC program, write it in assembly language, then assemble it with CHASM. You should read page C-7 of the BASIC manual for some conventions to use in writing your subroutine. In particular, note that you must declare the routine to CHASM as a FAR procedure using the PROC pseudo-op, and that the last instruction of the routine should be a RET. For short routines, probably the easiest way to get the code into a BASIC program is to just hand copy the object code from the listing into a DATA statement. The BASIC program can then READ the data and POKE it into memory. An example program to do this is given on page C-6 of the BASIC manual. An alternative approach would be to store the routine in a string variable, which could later be located with the VARPTR function. You transfer control to your routine with either the USR function, or the CALL statement. Syntax for these statements can be found in the BASIC manual. XIII. Miscellaneous and A Word From Our Sponsor... There is a bewildering array of files on your disk. As you've discovered by now, the file CHASM.DOC is documentation, and need not be present for Chasm to run. Some of the others may need explanation, however. The actual program is in CHASM.BAS. To run the program, three other files *must* be present. You must copy BASIC.COM from your DOS disk to interpret the program. CHASM.DAT contains data about the various instruction mnemonics Chasm recognizes, and must be present. The last file needed is CHASM.OVL. OVL is an empty file, which is merged to fool BASIC into deleting some of the initialization code to make more room for the symbol table. The file CHASM.BAT is a batch file to make it easier to start Chasm from DOS. With CHASM.BAT, you can just type: chasm. Without it you'd type: basic chasm/c:0. TCHASM.BAT is a batch file use to breed new CHASM disks, if you want to give a copy to someone else. It copys the program, documentation, data; the whole works. Please only distribute the complete CHASM system, as generated by this batch file. {!} TCHASM.BAT is not related to TChasm.Pas that I'm distributing. Disclaimer: CHASM is distributed as is, with no guarantee that it will work correctly in all situations. I cannot be responsable for any damages associated with its use. Nonetheless, it is my intention to correct any genuine bugs which are brought to my attention. Drop me a line if you think you've found a problem. {!} The same disclaimer goes for me. I'm not able to guarantee that the program will work properly. It seems to work fine on my IBM PC. The Turbo Editor Toolbox contains routines which write directly to Video RAM, so if your computer isn't VERY compatible, you may have difficulty running the program. I am joining the experiment started by the folks at Freeware (tm), by distributing un-protected software, and *encouraging* copying. The catch, (of course there's a catch) is that I request that all users who think the program is worthwhile send a donation. The suggested donation is $20, but send what you think the program is worth to *you*. There is obviously no way I can enforce payment, but I hope people will recognize the amount of work that went into writing and documenting Chasm, and will make a donation. If the monetary response is great enough, I will release upgrades to this program (version 2.0 is already in the works) and other programs of comparible magnitude (future projects include a macro pre-processor to run in 64K for use with either CHASM or BASIC). I hope folks find CHASM useful. David Whitman Department of Chemistry Dartmouth College Hanover, NH 03755 (603) 643-2115